Creating property inspectors for locked content

Once you've created a translator, you'll need to create a property inspector for the content so that the user can change its properties (for example, the file to be included, or one of the conditions in a conditional statement). Inspecting translated content is a unique problem for several reasons:

	The user may want to change the properties of the translated content, and those changes must be reflected in the untranslated content.
	The DOM contains the translated content (that is, the lock tags and the tags they surround are nodes in the DOM), but the outerHTML property of the documentElement and the dreamweaver.getSelection() and dreamweaver.nodeToOffsets() functions act on the untranslated source.
	The tags you're inspecting are different before and after translation.

If the user might disable your translator, and another inspector is not already handling the untranslated tags, you may need to create two property inspectors—one for the untranslated tag or tags, and one for the locked region created by translation. The interfaces of the two inspectors can be identical, but the comment at the top of the file and the canInspectSelection() and inspectSelection() functions—must differ.

For example, an inspector for the HAPPY tag might have a comment that looks like this:

<!-- tag:HAPPY,priority:5,selection:exact,hline,vline -->

The inspector for the translated HAPPY tag, however, would have a comment that looks like this:

<!-- tag:*LOCKED*,priority:5,selection:within,hline,vline -->

The canInspectSelection() function for the untranslated HAPPY inspector is simple: since the selection type is exact, it can return TRUE without further analysis. For the translated HAPPY inspector, this function is more complicated; the keyword *LOCKED* indicates that the inspector is appropriate when the selection is within a locked region, but because a document could have several locked regions, further checks must be performed to determine if the inspector matches this particular locked region.

Yet another problem is inherent in inspecting translated content. When you call dom.getSelection(), the values returned by default are offsets into the untranslated source. To expand the selection properly so that the locked region (and only the locked region) is selected, use the following method:

var currentDOM = dw.getDocumentDOM();
var offsets = currentDOM.getSelection();
var theSelection = currentDOM.offsetsToNode(offsets[0],offsets[0]+1);

Using offsets[0]+1 as the second argument assures that you remain within the opening lock tag when you convert the offsets to a node. If you use offsets[1] as the second argument, you risk selecting the node above the lock.

Once you have the selection (after first making sure that its nodeType node.ELEMENT_NODE), you can inspect the type attribute to see if the locked region matches this inspector. For example:

if (theSelection.nodeType == node.ELEMENT_NODE && theSelection.getAttribute('type') == 'happy'){
  return true;
}else{
  return false
}

To populate the fields in the inspector for the translated tag, you must parse the value of the orig attribute. For example, if the untranslated code is <HAPPY TIME="22"> and the property inspector has a field labeled Time, you must extract the value of the TIME attribute from the orig string.

function inspectSelection() {
  var currentDOM = dw.getDocumentDOM();
  var currSelection = currentDOM.getSelection();
  var theObj = currentDOM.offsetsToNode(curSelection[0],curSelection[0]+1);

  if (theObj.nodeType != Node.ELEMENT_NODE) {
    return;
  }

  // To convert the encoded characters back to their
  // original values, use the unescape() method.
  var origAtt = unescape(theObj.getAttribute("ORIG"));
  
  // Convert the string to lower case for processing
  var origAttLC = origAtt.toLowerCase();

  var timeStart = origAttLC.indexOf('time="');
  var timeEnd = origAttLC.indexOf('"',timeStart+6);
  var timeValue = origAtt.substring(timeStart+6,timeEnd);

  document.layers['timelayer'].document.timeForm.timefield.value = timeValue;
}

Once you've parsed the orig attribute in order to populate the fields in the property inspector for the translated tag, your first instinct is probably to set the value of the orig attribute if the user changes the value in any of the fields. This is not the best course of action, however, as you are likely to run into the restriction against making changes in a locked region. You can avoid this problem by changing the original markup and then retranslating.

The property inspector for translated server-side includes (Configuration/Inspectors/ssi_translated.js) demonstrates this technique in its setComment() function. Rather than rewriting the orig attribute, the inspector assembles a new SSI comment. It then inserts that comment into the document in place of the old one by rewriting the entire document contents, which in turn generates a new orig attribute. The following code summarizes this technique:

// Assemble the new include comment. radioStr and URL are 
// variables defined earlier in the code.
newInc = "<!--#include " + radioStr + "=" + '"' + URL + '"' +" -->";

// Get the contents of the document.
var entireDocObj = dreamweaver.getDocumentDOM();
var docSrc = entireDocObj.documentElement.outerHTML;

// Store everything up to the SSI comment and everything after
// the SSI comment in the beforeSelStr and afterSelStr variables.
var beforeSelStr = docSrc.substring(0, curSelection[0] );
var afterSelStr  = docSrc.substring(curSelection[1]);

// Assemble the new contents of the document.
docSrc = beforeSelStr + newInc + afterSelStr;

// Set the outerHTML of the HTML tag (represented by
// the documentElement object) to the new contents,
// and then set the selection back to the locked region
// surrounding the SSI comment.
entireDocObj.documentElement.outerHTML = docSrc;
entireDocObj.setSelection(curSelection[0], curSelection[0]+1);